Ophangen of netjes communiceren

Stel je voor: je belt een webshop om te vragen of product X nog op voorraad is. De medewerker aan de andere kant zegt: "Nee, helaas niet meer leverbaar." Wat zou je vinden als diegene vervolgens direct de hoorn erop gooit?

Waarschijnlijk zeer onprofessioneel. Want zelfs als het antwoord 'nee' is, verwacht je toch een normaal gesprek. Misschien kun je vragen of het product nog komt, of dat er een alternatief is.

Precies zo kijken wij naar API-communicatie.

Het probleem met traditionele API's

In de wereld van API's is het gebruikelijk om veel te werken met verschillende HTTP-statuscodes:

200 - Success (bericht is goed verwerkt)
400 - Bad Request (je vraag klopt niet)
404 - Not Found (kan het niet vinden)
500 - Server Error (er ging iets mis)

En daar zit direct het probleem, vooral met 404. Want wat betekent een 404 eigenlijk?

De URL die je aanroept bestaat niet
De data die je opvraagt bestaat niet

Voor een developer die een koppeling bouwt is dit verwarrend. Wanneer er een 404 terugkomt, is dan:

De API-aanroep verkeerd?
De endpoint-configuratie onjuist?
Het opgevraagde artikel simpelweg niet in voorraad?

Je weet het niet. De verbinding is verbroken.

Onze filosofie: de lijn open houden

Bij Conneo kiezen we bewust voor een andere aanpak. Net zoals je in een normaal gesprek niet zomaar de hoorn erop gooit, houden wij de communicatielijn open en geven we een duidelijk antwoord.

Daarom gebruiken wij waar mogelijk altijd HTTP status 200 (OK).

Klinkt gek? Niet als je het vanuit communicatie bekijkt. Status 200 betekent:

"Dank voor je bericht. We hebben het ontvangen, verwerkt, en hier is onze reactie."

Hoe werkt dat in de praktijk?

Al onze API's hebben een standaard response-structuur:

{
  "meta": {
    "status": "success",
    "message": "Product gevonden"
  },
  "data": {
    "productId": "12345",
    "naam": "Brochure A4",
    "voorraad": 150
  }
}

En wanneer een product niet gevonden wordt?

{
  "meta": {
    "status": "error",
    "message": "Product met ID 99999 niet gevonden"
  },
  "data": null
}

De HTTP-statuscode? Nog steeds 200.

Want de verbinding werkt perfect. Je vraag is aangekomen. We hebben ernaar gekeken en geven je een duidelijk antwoord: dit product bestaat niet in ons systeem.

De voordelen voor developers

Deze aanpak heeft concrete voordelen voor iedereen die met onze API's werkt:

1. Duidelijkheid bij debuggen

Krijg je geen HTTP 200 terug? Dan is er echt iets mis met de verbinding of de endpoint. Krijg je wel 200? Check dan de meta.status om te zien of je request succesvol was.

2. Consistente error handling

Je hoeft niet voor elk type fout andere HTTP-statuscodes af te vangen. Eén simpele check op meta.status volstaat:

if (response.meta.status === 'success') {
  // Verwerk de data
  processData(response.data);
} else {
  // Toon de foutmelding
  showError(response.meta.message);
}

3. Betekenisvolle foutmeldingen

In plaats van cryptische HTTP-statuscodes krijg je heldere Nederlandse berichten:

"Geen voorraad beschikbaar voor dit artikel"
"Klant met dit e-mailadres bestaat al"
"Leverdatum ligt in het verleden"

4. Betere gebruikerservaring

Omdat de foutmeldingen duidelijk zijn, kun je ze direct aan eindgebruikers tonen zonder vertaalslag. Ze snappen wat er aan de hand is en wat ze kunnen doen.

Wanneer gebruik je wél andere statuscodes?

Natuurlijk zijn er uitzonderingen. Bij onverwachte, niet-afgevangen fouten krijg je wel een 500 (Server Error). Dit betekent: er is iets misgegaan wat wij niet hadden voorzien. Dan is het terecht dat de statuscode dit aangeeft.

Ook voor authenticatie gebruiken we standaard HTTP-codes:

401 - Niet geauthenticeerd
403 - Geen toegang

Dit zijn situaties waarbij de verbinding wel werkt, maar je eerst moet inloggen of andere rechten nodig hebt.

Vriendelijke API's in de praktijk

Deze filosofie past perfect bij onze Noabership-aanpak. Wij geloven in transparante, begrijpbare oplossingen waarbij samenwerking centraal staat.

Een voorbeeld: een klant koppelt zijn webshop aan zijn productiesysteem via onze API. Wanneer een klant een product bestelt dat op dat moment niet leverbaar is, krijgt de webshop niet een cryptische 404-error. In plaats daarvan krijgt hij:

{
  "meta": {
    "status": "error",
    "message": "Product tijdelijk niet op voorraad, levertijd 5-7 werkdagen"
  },
  "data": {
    "productId": "12345",
    "verwachteLeverdatum": "2025-11-26"
  }
}

De webshop kan nu intelligent reageren: de klant krijgt direct te zien dat het product niet direct leverbaar is, maar wel wanneer het verwacht wordt. Veel beter dan een generieke "Product niet gevonden" melding.

Het verschil tussen technisch correct en gebruiksvriendelijk

Ja, je zou kunnen zeggen dat HTTP 404 technisch correct is voor "data niet gevonden". En ja, veel API-standaarden werken zo.

Maar wij kiezen bewust voor gebruiksvriendelijk boven technisch purisme.

Want uiteindelijk gaat het erom dat:

Developers sneller kunnen bouwen
Fouten makkelijker te debuggen zijn
Eindgebruikers begrijpelijke meldingen krijgen
Integraties betrouwbaarder werken

En dat bereik je niet door je strikt aan conventies te houden, maar door na te denken over wat écht helpt.

Benieuwd naar onze API's?

Werk je aan een koppeling en wil je ervaren hoe een vriendelijke API-benadering werkt? Of ben je benieuwd of wij jouw systemen kunnen koppelen met onze aanpak?

Plan een vrijblijvende belafspraak en ontdek hoe wij communicatie centraal stellen in onze integraties.

Of bekijk eerst onze Noabership-pagina om meer te lezen over onze werkwijze waarbij we naast je staan bij automatisering en integraties.

Want net als in een goed gesprek: ophangen is nooit de oplossing. Duidelijk communiceren wel.

API's die niet ophangen